---
title: "Chart Customisation"
enterprise: true
---

Integrated Charts can be customised via the [AG Charts Theme API](https://www.ag-grid.com/charts/themes-api/).

## Provided Themes

The following themes are provided to Integrated Charts by default.

```js
['ag-default', 'ag-material', 'ag-sheets', 'ag-polychroma', 'ag-vivid']
```

These themes correspond to [AG Charts Base Themes](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-baseTheme).

{% note %}
When using a dark colour scheme for the grid, the application must provide the dark equivalents of the chart themes. If a default AG Chart theme is used, the dark themes are named with a `-dark` suffix, e.g. `'ag-vivid-dark'`.
{% /note %}

The selected theme can be changed by the user via the [Chart Tool Panel](./integrated-charts-chart-tool-panels/) or
by changing the order of the provided themes using the `chartThemes` grid option as shown below:

```{% frameworkTransform=true spaceBetweenProperties=true %}
const gridOptions = {
    chartThemes: ['ag-vivid', 'ag-polychroma', 'ag-material', 'ag-sheets', 'ag-default']
}
```

## Overriding Themes

Integrated Charts uses a theme based configuration which 'overrides' the theme defaults.

To override a charts theme, use the `chartsThemeOverrides` grid option.

```{% frameworkTransform=true %}
const gridOptions = {
    chartThemeOverrides: {
        common: {
            title: {
                fontSize: 22,
                fontFamily: 'Arial, sans-serif'
            }
        }
    }
}
```

{% note %}
Note that the `chartThemeOverrides` grid option maps to [AG Charts Theme Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides).
{% /note %}

### Common Overrides

These overrides can be used with any series type. For full list of overrides see [Common Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-common) in the AG Charts documentation.

{% gridExampleRunner title="Common Overrides" name="common-overrides"  exampleHeight=660 /%}

### Chart-specific Overrides

The following documentation links describe different types of overrides specific to individual AG Charts series types.

* [Line Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-line)
* [Bar Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-bar)
* [Area Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-area)
* [Scatter Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-scatter)
* [Pie Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-pie)
* [Radar Line Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-radar-line)
* [Radar Area Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-radar-area)
* [Nightingale Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-nightingale)
* [Radial Column Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-radial-column)
* [Radial Bar Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-radial-bar)
* [Range Bar Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-range-bar)
* [Range Area Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-range-area)
* [Box Plot Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-box-plot)
* [Waterfall Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-waterfall)
* [Heatmap Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-heatmap)
* [Treemap Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-treemap)
* [Sunburst Overrides](https://www.ag-grid.com/charts/themes-api/#reference-AgChartTheme-overrides-sunburst)

## Custom Chart Themes

Custom [AG Charts Themes](https://www.ag-grid.com/charts/react/themes/) can also be supplied to the grid via the `customChartThemes` grid option.

```{% frameworkTransform=true spaceBetweenProperties=true %}
const gridOptions = {
    customChartThemes: {
        myCustomTheme: {
            palette: {
                fills: ['#42a5f5', '#ffa726', '#81c784'],
                strokes: ['#000000', '#424242'],
            },
            overrides: {
                common: {
                    background: {
                        fill: '#f4f4f4',
                    },
                    legend: {
                        item: {
                            label: {
                                color: '#333333',
                            },
                        },
                    },
                },
            },    
        },
        chartThemes: ['myCustomTheme', 'ag-vivid'],
    }
}
```

The example below shows a custom chart theme being used with the grid. Note that other provided themes can be used
alongside a custom theme, and are unaffected by the settings in the custom theme.

{% gridExampleRunner title="Custom Chart Theme" name="custom-chart-theme"  exampleHeight=660 /%}

## Formatting

Chart values can be formatted in several different ways.

### Label Formatting

{% note %}
The `valueFormatter` is not automatically applied to the chart axes. If you wish to use the grid's value formatters, you must apply them manually.
{% /note %}

Custom label formatting can be applied to the chart axes by providing suitable formatters.

```{% frameworkTransform=true spaceBetweenProperties=true %}
const gridOptions = {
    chartThemeOverrides: {
        common: {
            axes: {
                number: {
                    label: {
                        formatter: function(params) {
                            // prefix with dollar sign
                            return '$' + params.value;
                        },
                    },
                },
            },
        },
    },
}
```

The example below shows:
* A custom label formatter being used with the vertical axis to display SI units for the data. Additionally,
this example demonstrates the use of the `domain` property passed through to the formatter to provide a consistent scale across the value range.
* A custom title formatter using `boundSeries` property passed through to the formatter for the vertical axis to display which series the axes are representing.

{% gridExampleRunner title="Label Formatting" name="label-formatting"  exampleHeight=660 /%}

For more information on the `formatter` property for axes labels, see AG Charts Axis Labels [Label Text Formatting](https://www.ag-grid.com/charts/javascript/axes-labels/#label-text-formatting).

### Global Formatter

A single, top‑level `formatter` can be used to control the text for every label‑bearing element, e.g. axes, series labels, legend items, callouts, etc. The formatter will run for each element, unless that element defines its own `formatter`.

The callback receives the similar `params` object provided to element‑level formatters, providing access to properties such as `value`, `type`, and `elementId`. See the [AG Charts API Reference](https://charts.ag-grid.com/themes-api/#reference-AgChartTheme-overrides-common-formatter) for more information.

```{% frameworkTransform=true %}
const gridOptions = {
    chartThemeOverrides: {
        common: {
            formatter: (params) => {
                if (params.type === 'number') {
                    return `£${params.value}`;
                    // prefix with `£` sign
                }
                const gridApi = params.context.api;
                // do something with the grid API
            }
        }
    }
}
```

The example below shows a global formatter that prefixes all number values with a `£` symbol.

{% gridExampleRunner title="Global Label Formatter" name="global-label-formatter"  exampleHeight=850 /%}

The order of formatting is as follows:

1. Element‑specific `label.formatter` (axis, series, legend, callout, etc.)
2. Global `formatter`
3. Default AG Charts formatting rules

### Accessing Grid Context in Formatters

The grid will pass the grid API and context into the `context` property of the formatter parameters.

{% interfaceDocumentation interfaceName="GridChartContext" /%}

For formatters that are directly linked to row data, the row node will be passed in the `datum.node` property (note that `datum` may be undefined).

For formatters related to columns, the `key` property will usually contain the column ID. In some instances this will be in the `key` property of the corresponding series in the `boundSeries` property.

In the example below, the global formatter is used to access the `valueFormatter` in each of the columns:
- The x axis uses the **Financial Period** column value formatter.
- The y axis does not use a formatter as it belongs to multiple columns.
- The tooltip (when mousing over the series) uses the value formatters from each of the three columns.

{% gridExampleRunner title="Formatter Context" name="formatter-context"  exampleHeight=850 /%}

## Next Up

Continue to the next section to learn about [Chart Events](./integrated-charts-events/).
